Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildbetter.ai/llms.txt

Use this file to discover all available pages before exploring further.

You shipped a new feature. You updated the UI. You changed how something works. But did you update the docs? Your help center is now lying to customers. They follow the steps, it doesn’t work, they open a ticket frustrated. This guide shows you how to identify which docs are outdated and update them systematically.

​
The Outdated Docs Problem

What happens after product changes:
  • 🚢 Team ships feature updates
  • 📚 Docs team (if you have one) doesn’t know
  • ❓ Customers follow old docs, get confused
  • 😤 Support tickets: “This doesn’t work!” (it does, docs are wrong)
  • 🔥 More tickets from outdated docs than from no docs
The truth: Outdated documentation is worse than no documentation. It wastes customer time AND support time.

​
What You’ll Achieve

With BuildBetter:
  • ✅ Identify outdated docs from customer questions
  • ✅ Prioritize updates by customer impact
  • ✅ Find UI changes customers are confused by
  • ✅ Keep docs in sync with product changes
  • ✅ Prevent documentation debt
Time investment: 30 mins/week to review + 1-2 hours/month for updates. Impact: Prevent 10-20 “docs are wrong” tickets/month.

​
Prerequisites

BuildBetter account with support tickets or customer calls
Existing help documentation
Product change log or release notes

​
Step 1: Find Documentation Gaps

[screenshot: Support tickets mentioning “doesn’t work” or “can’t find”]
1

Import Recent Support Tickets

Focus on tickets AFTER your last product release:
  1. Import last 30 days of tickets
  2. Filter for common phrases:
    • “Doesn’t work”
    • “Can’t find”
    • “Instructions wrong”
    • “Not where it says”
[screenshot: Filtered signals showing documentation complaints]
2

Ask Chat to Find Documentation Issues

Query: “Which help articles or documentation are customers saying is incorrect or outdated? What are they confused about?”[screenshot: Chat identifying outdated doc patterns]Example output:
Outdated Documentation Identified (Last 30 Days):

1. "How to Export Data" Article (14 tickets)
   Customer complaints:
   - "Export button not in top right anymore"
   - "Don't see CSV option mentioned in article"
   - "Steps don't match what I see"

   Root cause: UI changed in v2.3, docs not updated

2. "Adding Team Members" Article (9 tickets)
   Customer complaints:
   - "Settings menu looks different"
   - "Can't find 'Invite' button where article says"

   Root cause: Settings redesigned last month

3. "API Authentication" Article (7 tickets)
   Customer complaints:
   - "API key generation different now"
   - "Screenshot shows old UI"

   Root cause: API dashboard updated

​
Step 2: Cross-Reference Product Changes

[screenshot: Product changelog with dates]
1

Review Recent Product Changes

Check your changelog/release notes:
  • Which features changed?
  • What UI updates shipped?
  • Which workflows are different?
Map to help docs:
  • Feature changed → Which articles mention it?
  • UI updated → Which screenshots are outdated?
  • Workflow different → Which step-by-step guides need updates?
2

Identify High-Impact Updates

Query: “Based on customer tickets, which product changes are causing the most confusion? Prioritize by ticket volume.”Focus on updating docs for changes that:
  • Generated most tickets
  • Affect most common workflows
  • Impact new users (onboarding docs)

​
Step 3: Update Documentation Systematically

[screenshot: Side-by-side comparison - old doc vs updated doc]
1

Create Update Queue

Query: “Generate a prioritized list of documentation updates needed, with: article name, what changed, urgency (high/medium/low), and estimated effort.”Example output:
Documentation Update Queue:

🔴 HIGH PRIORITY
1. "How to Export Data"
   - What changed: Button moved from top right to Reports menu
   - Urgency: HIGH (14 tickets in 30 days)
   - Effort: Low (update 2 screenshots, change 1 sentence)
   - Impact: Prevents ~5 tickets/week

2. "Adding Team Members"
   - What changed: Settings menu redesigned
   - Urgency: HIGH (9 tickets)
   - Effort: Medium (update 3 screenshots, rewrite steps)
   - Impact: Prevents ~3 tickets/week

🟡 MEDIUM PRIORITY
3. "API Authentication"
   - What changed: New API dashboard
   - Urgency: MEDIUM (7 tickets, but power users)
   - Effort: High (complete rewrite needed)
   - Impact: Prevents ~2 tickets/week
2

Update Articles

For each article:Before you start:
  1. Open the app/feature yourself
  2. Go through the current steps
  3. Take new screenshots
  4. Note what’s different
Update process:
  1. Update screenshots (highlight new UI elements)
  2. Revise step-by-step instructions
  3. Test: Can someone follow these new steps?
  4. Add “Last updated: [Date]” to article
  5. Publish
Pro tip: Use Chat to help rewrite
  • Query: “Rewrite this help article based on the new UI. Old steps: [paste old]. New UI: [describe changes].”
3

Add Change Indicators

In help center:
  • Tag recently updated articles: ”✅ Updated for v2.3”
  • Show last updated date prominently
  • Add changelog at bottom: “What changed in this article”
[screenshot: Help article with “Updated Mar 2024” badge]Helps customers know docs are current.

​
Step 4: Prevent Future Documentation Debt

[screenshot: Documentation workflow integrated into release process]
1

Create Documentation Review Workflow

Before each release:
  1. Product team shares changelog
  2. Review which help docs are affected
  3. Update docs BEFORE feature ships
  4. Mark as “Updated for vX.X”
After each release:
  1. Week 1: Monitor support tickets for confusion
  2. Week 2: Update docs based on real customer questions
  3. Week 4: Ask Chat: “Any new documentation gaps this month?”
2

Set Up Monthly Documentation Audit

First Monday of each month (30 mins):Query Chat:
  • “Which help articles got the most ‘this didn’t work’ tickets last month?”
  • “Are there new customer questions we don’t have docs for?”
  • “Which articles might be outdated based on product changes?”
[screenshot: Monthly documentation health report]Update 2-3 articles per month minimum.
3

Track Documentation Health

Metrics to monitor:
  • Tickets mentioning “docs wrong” or “doesn’t match”
  • Help article deflection rate (views vs tickets)
  • “Not helpful” feedback on articles
  • Articles with >6 months since update
[screenshot: Documentation health dashboard]Good signal: Deflection rate stable or improving Bad signal: Deflection rate declining (docs getting outdated)

​
Real Example: Jamie’s Documentation Maintenance

Background: Jamie is Head of Support. Good help docs. But product ships weekly. Docs always outdated. The Problem:
  • Product team ships, doesn’t tell support
  • Support finds out when customers complain
  • Docs perpetually 2-3 weeks behind
  • “Docs are wrong” became most common ticket
The Solution (with BuildBetter): Week 1: Set up monitoring
  • Import all support tickets
  • Filter for documentation complaints
  • Found 23 tickets in last month about wrong docs
Week 2: Audit existing docs
  • Cross-referenced with recent product changes
  • Found 8 articles outdated
  • Prioritized by ticket volume
  • Updated top 5 (3 hours total)
Week 3: Created weekly workflow
  • Monday: Product team shares changelog
  • Tuesday: Jamie reviews which docs affected
  • Wednesday: Updates docs before feature ships
  • Friday: Check for any surprise confusion
Month 1: Automated monitoring
  • Monthly Chat query: “Documentation gaps?”
  • Review outdated article list
  • Update 2-3 per month
Results after 90 days:
  • “Docs are wrong” tickets: 23/month → 4/month (-83%)
  • Documentation deflection rate: 45% → 68%
  • Customer satisfaction with docs: 3.2/5 → 4.4/5
  • Time spent updating: 1 hour/week (sustainable)
Jamie’s quote: “We went from reactive (fix docs after customers complain) to proactive (update docs before feature ships). BuildBetter tells us which docs need attention before they become a support burden.”

​
Best Practices

Update BEFORE shipping: Include doc updates in your definition of “done” for features
Date your articles: Show “Last updated: March 2024” so customers know freshness
Small updates weekly > Big updates quarterly: Easier to maintain currency
Screenshot liberally: Outdated screenshots = most common complaint
Test your own docs: Follow the steps yourself before publishing updates
Archive old versions: Don’t delete, mark as archived for older product versions

​
Common Questions

Prioritize by:
  1. Customer complaints (ticket volume)
  2. Common workflows (affects most users)
  3. New user docs (onboarding critical)
  4. Recent product changes (most likely outdated)
Use BuildBetter to surface #1 automatically.
Depends on impact:✅ Update if:
  • Buttons moved or renamed
  • Steps don’t work anymore
  • Screenshots clearly wrong
  • Causing tickets
⏸️ Don’t update if:
  • Minor color/style changes
  • Functionally identical
  • Not causing confusion
Let customer tickets guide you.
Triage approach:
  • Breaking changes: Update docs same day
  • New features: Update within 3 days
  • Minor tweaks: Batch update weekly
  • Bug fixes: Usually don’t need doc updates
Monitor tickets to see if something needs immediate attention.
Build it into process:
  1. Add “Documentation updated?” to PR checklist
  2. Automatic Slack post: “Feature X shipped. Docs need review?”
  3. Use BuildBetter as safety net (finds gaps from tickets)
Or: Weekly sync with product team on upcoming changes

​
Documentation Maintenance Checklist

​
Weekly (30 mins)

Review product changelog for doc-affecting changes
Update docs for shipped features (before release if possible)
Check for “docs wrong” tickets this week

​
Monthly (1-2 hours)

Ask Chat: “Documentation gaps from last month?”
Update 2-3 most outdated articles
Review help article metrics (views, deflection)
Update screenshots for UI changes

​
Quarterly (Half day)

Full documentation audit
Archive docs for sunset features
Reorganize/restructure if needed
Review documentation health metrics

​
Next Steps

Write New Documentation

Create help docs from customer questions

Reduce Support Tickets

Full ticket deflection strategy

Document Generation

Auto-generate docs from patterns

Knowledge Management

Organize all your documentation
Good documentation isn’t written once—it’s maintained continuously.
The best support teams treat documentation like code: version it, review it, update it with every release. Outdated docs create more problems than they solve.
Based on analysis of 200+ support teams. Teams that update docs within 1 week of product changes see 40% fewer “docs are wrong” tickets than teams that batch update monthly.